Summary

• New docs/secret-cache.md — authoritative reference for the secret cache feature shipped in PRs Add encrypted secret cache to survive provider outages #15–Fix serve quadlet: SELinux label and ready-signal healthcheck #18.
• README updates covering the new cache: config block, the psi cache CLI subcommands, and the FCOS deployment impact.
• Infisical and Nitrokey HSM provider docs updated to reflect current behavior (cache-aware lookup path, current generator output, corrected security model table, fixed stale service name).
• CLAUDE.md package layout and CLI reference updated for psi/cache.py, psi/cache_backends.py, and the psi cache subcommands.
• All deployment-specific examples (project names, instance URLs) replaced with neutral placeholders.

What's in docs/secret-cache.md

• Context — why the cache exists, the failure mode it addresses
• How it fits in — setup fetch path and lookup hot path diagrams
• Threat model — what the cache does and does not defend against, and the explicit trade-off that it introduces secrets-at-rest
• Configuration — cache: block fields, default behavior when unset
• Backends — TPM2 via systemd-creds and Nitrokey HSM via PKCS#11, when to pick each, trade-offs
• On-disk envelope format — header bytes, TPM payload shape, HSM payload shape, inner JSON
• CLI reference — psi cache init/status/refresh/invalidate with examples
• Deployment walkthroughs — native TPM, container TPM, container HSM (the full podman run one-shot pattern for container-mode installs)
• Cold-boot caveat — the cache only protects against outages after it has been populated at least once
• Rotation — psi cache refresh and psi cache invalidate workflows
• Troubleshooting — regression symptoms and fixes for the bugs caught during rollout (missing HSM wiring, slow status, backend tag mismatch, HealthStartPeriod too short)

README changes

• How it works block now shows the in-memory dict hot path and mentions the cache file at startup
• New Secret cache configuration subsection with a short example, the two backends summarized, and a link to the reference
• New Secret cache CLI reference subsection listing psi cache init|status|refresh|invalidate
• FCOS deployment section notes that the generator auto-emits HSM/TPM wiring to both psi-secrets.container and psi-{provider}-setup.container when the cache is configured, and that workloads using the nitrokeyhsm provider without the cache still need manual quadlet wiring
• Clarifies the psi systemd install --mode container one-shot invocation works inside a psi container — with a link to the full recipe in docs/secret-cache.md

Provider doc updates

docs/infisical-provider.md

• Top-level description now qualifies the "no secret values on disk" claim: it remains true only with the cache disabled, and qualified when enabled
• Setup section documents the new step 5: populate the encrypted cache bundle using the values already returned by list_secrets (no extra API calls)
• Lookup section rewritten to describe the cache-first hot path in _handle_lookup
• Security model table rewritten with separate rows for "cache disabled" and "cache enabled"
• Fixes the stale psi-secrets-setup.service reference → psi-infisical-setup.service (the real unit name)

docs/nitrokeyhsm-provider.md

• Example serve quadlet updated to match current generator output: ContainerName=psi-secrets, SecurityLabelType=container_runtime_t, Notify=healthy, HealthCmd, HealthStartPeriod=60s
• Image tag corrected from :dev to :latest
• Short note explaining that psi systemd install --mode container emits all of this automatically when cache.backend: hsm is set

CLAUDE.md

• Package layout block adds psi/cache.py and psi/cache_backends.py with one-line descriptions
• Module dependency arrows add the cache and helper relationships (serve.py → cache.py, setup.py → cache.py, cache_backends.py → providers/nitrokeyhsm, etc.)
• CLI commands block adds the four psi cache subcommands
• Fixes the same stale psi-secrets-setup.service example that was in docs/infisical-provider.md

Test plan

• uv run pytest -q — 296 passed (no code changes)
• grep -rn 'homelab\|inf7\.dev' README.md CLAUDE.md docs/ — empty
• Preview render on GitHub to confirm the Markdown tables and code blocks in docs/secret-cache.md look right